\documentclass[a4paper,10pt]{article}
\usepackage[utf8x]{inputenc}
\usepackage[cm]{fullpage}

%opening
\title{Course Diary - Entry \#4\\
475 Advanced Topics in Software Engineering}
\author{Eli Gutin \texttt{eg08}, \\ Michael Kwan \texttt{mk08}, \\ John Wong \texttt{jw808} }

\begin{document}

\maketitle

\section{Three key points from the lecture}

\begin{itemize} 
\item{The importance of well structured and logically organised systems and its effects upon (re)usability, readability and maintainability. One of the focuses of this part of the lecture was dependency 
cycles and how they break the intended layering of the code and hence prevent reuse of individual elements. We learned about the abstract client and abstract server patterns which allow decoupling of these cycles by 
exposing an interface upon which other packages and classes interact against rather than 'knowing' about and acting upon instances of the concrete class itself.}
\item{Dependency injection leads on from the above concepts, providing a way for the objects to interact by some class 'higher up' performing the wiring up. This can be achieved through code, configuration files as 
well as annotations. The ultimate outcome is that the 'client' and 'server' classes are insulated against each others' implementations. On top of improving the code in the way the 'effects' above summarise, when used with 
abstract server and abstract client patterns, dependency injection promotes unit testing by increasing interoperability of classes, allowing test units to be slotted in easily.}
\item{Layering is placing smaller working systems at the bottom and building on top of them with each upper layer knowing only about the systems either below it or directly below it depending on the variant/style employed. It provides 
a way of abstracting implementation details, with each layer providing an API for upper layers to interact against. This allows individual implementations to be changed as long as they continue to adhere to the 
API. This principle extends to frameworks which can also be layered upon each other but require more considerations. In the case of a framework, a balance needs to be drawn between a generic and reusable implementation against a more precise solution which 
performs only its required function (and requires less manpower) but is perhaps not as generic.}
\end{itemize}

\section{Related Reading}
We went through an article written by Robert C. Martin \\ (\texttt{http://www.objectmentor.com/resources/articles/Principles\_and\_Patterns.pdf}) about Design Principles and Design Patterns.
He stated that the design of a software 'rots' - becomes unclean and more complex as the engineer proceeds through minor changings to preserve functionality during the development.
He clearly listed out the four symptoms of a rotting design:
\begin{itemize} 
\item{\textbf{Rigidity} : The difficulty to change a part or a feature of the software. Usually overcome by making a cascade of subsequent changes in dependent modules.}
\item{\textbf{Fragility} : Software which are vulnerable to minor modifications and will be broken down into pieces if so, making the software impossible to maintain without introducing other problems.}
\item{\textbf{Immobility} : Software which totally designed and customised only for certain applications, which means the parts and features of it are not reusable on some other projects.}
\item{\textbf{Viscosity(design)} : Software which are difficult to employ the design preserving methods when it comes to a task of modifying the software.}
\item{\textbf{Viscosity(environment)} : Software which are slow and inefficient, which do not encourage engineers to make big changes when required to, regardless of whether the changes are optimal.}
\end{itemize}
He then went through techniques to avoid designs rotting such as the \textbf{Open Closed Principle (OCP)} and \textbf{Liskov Substitution Principle (LSP)} which make software easier to be extended rather than to be modified. 

As we look deep into some structuring concepts, there is another article written by Martin Fowler (\texttt{http://martinfowler.com/articles/injection.html}) which talks about Dependency Injection, which is a design principles to avoid heavyweight complexity when combining the interfaces and contracts from other developers.
In the article, he mentioned the basic concept of it is to create a separater object class between two object classes in order to remove the dependencies within. In this design pattern approach, he introduced three types of injections:
\begin{itemize} 
\item{\textbf{Constructor Injection} : Having the target class declare a constructor that includes everything it needs injected.}
\item{\textbf{Setter Injection} :  Having the target class define setter methods which include all the injecting elements.}
\item{\textbf{Interface Injection} :  Having the target class define and use interfaces for the injection.}
\end{itemize} 
He also mentioned an alternative method to break dependencies - using a \texttt{Service Locator}, which is to create a object class which contains all the features that the application might need. On top of it, a segregated interface or a dynamic service locator can also be used for the locator so that it can be flexible on what services need to be declared and used.
He then brought up the advantages and disadvantages of these two techniques and analysed various scenarios which each of them can be used better.

\section{Similar Past Projects}
\subsection{Mike's experience}
In my 6 months in industry, I worked in an infrastructure team creating proprietary library components. My main project was to develop a framework for real users who had varying requirements and needs. I identified 
with many of the issues discussed in the lecture and faced a lot of the same issues in reality. The 'registry' style of framework as described by the lecture is what I finally opted into using. I was also taught about dependency injection 
which allowed me to write unit tests for my framework.

\subsection{Eli's experience}
During my industrial placement, one of the projects that my team worked on was
a piece of software that was roughly 3 years old and had a rapidly expanding user base when I joined.
It was tens of \emph{kloc} and there were constantly new requirements piling on and bugs that were being uncovered.

While it did have unit tests, the code was structured in an unusual way, with servers having intimate knowledge of the exact type of clients (and vice versa)
. Coding to interfaces was not adhered to and there were quite a few hacks in different places. It was difficult to balance the task of fixing the code structure
, fixing bugs and producing the features that were constantly being asked for. This experience showed me how in practice, it is difficult to achieve good structure for a very large project
but also how it would be extremely beneficial in the long if technical debt wasn't being accumulated.

\subsection{John's experience} 
In my experience, I've encountered related problems such as spending great amount of time to explore and understand the system of a given piece of software and even sometimes I struggled upon literal descriptions and explainations of the software. This is usually because of the bad structuring of the softwares and lots of cyclic dependencies between the classes. Problems like this even happened to myself with my own piece of work.

Back when I was working in one of the group projects in my University course two years ago, I wasn't familiar with any coding design and structuring principles. Therefore I developed my part of the application just with my coding instinct. After that, the group and I proceed with a lot of small changes in features and structural designs in order to improve the software for the project.  During this process, I went through a lot of pain and hustle to reconstruct my code instead of making some minor modifications to adapt the new requirements. I also had difficulties fitting the code to other team members' ones. These all due to the fact that my code wasn't well organised and the design was too rigid, fragile and immobile. As the difficulty to change my code accumulates, I eventually had no choice but to rebuild a new bunch of code. Having realised the problem I had, I took serious considerations and redesigned the code such that it was much better structured by using packages, modules, and layered abstractions. Overall, this project struck me as a lesson that the design and structuring runs a very important role when it comes to developing a new application and disasters can be easily caused by not having such knowledge and awareness.

\section{Tutorial Exercise Description}
The first half of the tutorial exercise was based on an example project which was shown in the lecture - \texttt{Smartcards}. 
The first objective for this project was to eliminate all the cyclic dependencies existing between the classes (i.e.: \texttt{cardholder} and \texttt{smartcard}, \texttt{smartcard} and \texttt{application delivery channel})
by employing the abstract client/server patterns as demonstrated in the lecture. 
The second objective was to introduce a new class \texttt{CompanyCardHolder} which has both dependencies of the classes \texttt{cardholder} and \texttt{request} (i.e.: it should have the instance of \texttt{application}, \texttt{cardholder} and \texttt{application delivery channel}. And it should be able to have accesses to all these instances' methods.). It is recommended that the class \texttt{CompanyCardHolder} should not be inherited from \texttt{cardholder} in order to avoid the properties of \texttt{CompanyCardHolder} being tangled by  the ones in \texttt{cardholder}.

The second half of the tutorial involved changing code from a real open-source project, the \texttt{JBidwatcher}. 
The first objective was to "purify" the \texttt{.auction} package which originally contained some dependencies on \texttt{UI} features 
(e.g. \texttt{JConfigEbayTab}) are in a package which only contains the \texttt{auction} features. 
The next aim was to remove the bad dependency from  the \texttt{auction} to the \texttt{ui} package. Finally we had to remove the dependencies from \texttt{.auction} to \texttt{.my}.

\section{Main Challenges}
One of the main challenges with the first part of the tutorial was that, while we had encountered the observer pattern and used it in the past,
we were fairly new to the idea of having abstract clients  and servers. For example the \texttt{CardHolder} was originally used as a concrete server
but then we had to think of which methods to extract into an interface and what to name the interface. We also had to think carefully about the layering aspects and ensure that there were no
'upward' dependencies, for instance if we didn't extract an interface for a \texttt{SmartCard} then there would be a circular dependency between the \texttt{cardholder} package to the
\texttt{smartcard} package. 

The second part of the tutorial, as described was more challenging. It was a much larger piece of code and there were many bad dependencies which needed fixing and 
were relatively subtle. For example, the \texttt{AuctionServer} had an accessor method for a GUI component (namely the \texttt{getServerConfigurationTabs}). This was called
from several different places. The reason why it was reasonably difficult to fix this dependency was because we needed to understand the purpose of that method and the reason why it was called from the \texttt{DoConfigure}
and \texttt{getUserSetup} methods in \texttt{UserActions} and \texttt{JBidWatch} before we could make our changes. This was a less mechanical process and really required us to understand the intention and higher level
semantics. 

In addition to quickly getting a good understanding of the code, the other challenging factor in the second part of the tutorial was the extensive use of the singleton pattern. 
This made it hard to adapt a server for different clients or have interoperable parts in an application. A notable example of this is from the ebay code where the \texttt{ebayBidder} was
calling the \texttt{MyJBidWatcher} singleton instance. This not only creates unnecessary and bad coupling, which we aimed to fix, but also would make writing tests infeasible because 
the unit test would be forced instantiate an \texttt{ebayBidder} which interacts with the specific \texttt{MyJBidWatcher} implementation. 
\section{Approaches}
For the \texttt{Smartcard} example, we needed to break cyclic dependencies using abstract clients/servers. First of all, we created  an abstract cardholder class 
called \texttt{CardHolder}, then renamed the original \texttt{CardHolder} to \texttt{CardHolderImpl} and \texttt{CompanyCardHolder} to 
\texttt{CompanyCardHolderImpl}. After this, to break the depedencies, it was a simple case of going through the code and ensuring that all parameters previously involving \texttt{CardHolder} (now renamed \texttt{CardHolderImpl}), 
used the CardHolder abstract class instead. This allows the code to program against the interface of the abstract class rather than be coupled to a particular implementation of it. In general, we try to 
use or declare the most 'generic' type which allows dependency injection at testing stages to easily swap out implementations with test implementations. For example, we refactored \texttt{CompanyCardHolderImpl consolidated = new CompanyCardHolderImpl(...)} to 
\texttt{CardHolder consolidated = new CompanyCardHolderImpl(...)}. One small extra change we needed was to wrap the \texttt{sendEmail/sendFax} functionality. We implemented an observer pattern by 
having a \texttt{sendNotification} message in the abstract class which wrapped \texttt{sendEmail/sendFax} respectively in the implementation classes. We performed similar refactoring for the \texttt{SmartCard} class, creating an abstract client class called \texttt{Card}. Finally, even though it was not required for the tutorial, we felt it was 
a good idea to refactor \texttt{OnlineDeliveryChannel} using abstract server. This futureproofs the code such that different implementations can be easily swapped in in the future.

For the \texttt{JBidWatcher} project, we needed to extract UI classes and details from the .auction package. The main problem was that the \texttt{AuctionServer} class within .auction should have been returning a
configuration mapping (string to array of string). However, it was returning this mapping wrapped in a UI object, \texttt{JConfigEbayTab}. The solution was to replace the \texttt{getConfigurationTabs} with 
a new method called \texttt{getConfigurationMapping} which instead returned a \texttt{Map<String, String[]>}. The abstract class, \texttt{AuctionServer} and all previous calls to the old 
method needed to be updated to reflect the new method signature. The parts in the UI using the mapping needed to iterate over the keyset of the returned \texttt{Map} and wrap them in \texttt{JConfigEbayTab} objects. 
Since the auction package no longer had a coupling to \texttt{JConfigEbayTab}, we could easily use eclipse to change which package that class lived in (to the UI, where it belongs).

The final part of the exercise involved removing the dependency from .auction to .my. The dependency was due to the reference to the \texttt{MyJBidWatcher} singleton. We fixed this by 
extracting \texttt{MyJBidWatcher} into an interface called \texttt{JBidWatcher} which we then made into a field instance of the auction class referencing \texttt{MyJBidWatcher}, 
\texttt{ebayBidder}. We had then modified the constructor of \texttt{ebayBidder} to accept an object implementing \texttt{JBidWatcher} which it assigned to the field instance.

\section{Feedback on the lecture/excercise}
We felt that, this particular lecture and tutorial was lacking in some ways to the previous ones we were given. We preferred having one hour of lecture, where 
we learn the theory and two hours of putting those ideas into practice. The reason for this was because it seemed for many people that the tutorial was a bit short 
and we had less time to ask helpers questions. Furthermore it was thought that the lecturer could have delivered the same amount content in less time. 

On the other hand, we liked how the lecture provided diagrams, and real world examples comparing well versus badly structured code bases. It was interesting to note
that the spring framework, had almost no undesirable dependencies and to compare it to ther projects. We liked how the lecturer told us of his experience in the industry
as that helped us to relate to the theory and principles that were taught. 
\end{document}